package persistence;

import java.util.Collection;

import util.NotFoundException;

/**
 * a class who provides low level persistence services. each such provider is parallel
 * to a single type of persistent object (i.e. that has unique id), and therefore to a
 * database table.
 * persistence works in transactions: to begin an operation, a transaction is started.
 * changes are not visible until the transaction is committed.
 *
 * @author idan
 */
public interface PersistenceController
{
	/** indicates to the constructor to build a new repository. */
	public static final boolean BUILD_NEW = false ;
	/** indicates to the constructor to load from repository. */
	public static final boolean LOAD = true ;

	/**
	 * close any connection to the persistence and perform cleanup operations.
	 * @post no actions can be performed on this controller.
	 */
	void close() ;

	/**
	 * flush the transaction to the persistent media.
	 * @throws RuntimeException if no transaction was started.
	 */
	void commitTransaction() throws RuntimeException ;

	/**
	 * delete an object from persistence.
	 * @param id id of the object to delete.
	 * @throws NotFoundException if no such object exists.
	 */
	void delete(long id) throws NotFoundException ;

	/**
	 * delete the all elements on the persistent media
	 * @post the persistent media contains no elements.
	 */
	void deleteAll() ;

	/**
	 * load an object from persistence (if needed).
	 * @param id id of the requested object.
	 * @return the requested object, or null if not found.
	 */
	Persistent get(long id) ;

	/**
	 * recover the entire persistence. this operation is expected to be expensive.
	 * @return the set of all objects in the persistent media.
	 */
	Collection<? extends Persistent> getAll() ;

	/**
	 * store an object to persistence (if needed).
	 * @param obj object to store.
	 * @post object will be assigned a new id.
	 */
	void put(Persistent obj) ;

	/**
	 * start a new transaction.
	 * an implementation may block until a previous transaction has committed.
	 */
	void startTransaction() ;
}
